Inside Macintosh: Open Transport /

Chapter 2 - Providers / Providers Reference

Functions / Sending Module-Specific Commands

MyNotifierCallbackFunction

After you install a notifier function on a provider, the provider calls the notifier function each time an Open Transport event occurs for that provider.

C INTERFACE

void MyNotifierCallbackFunction (void* contextPtr, OTEventCode code,
                                 OTResult result, void* cookie);

C++ INTERFACE

In C++, a notifier function can be either a C function (as in the C interface) or a member function of a class--the TOTProcNotifier class, the TOTMethodNotifier class, or a subclass of these. The return type and parameters of a notifier function are the same whether the notifier function is a C function or a C++ member function.

PARAMETERS

contextPtr

The value you specified for the contextPtr parameter when installing this notifier function. You can use this parameter in any way that is useful to you. If you do not need it, you can set the pointer to nil.

code

An event code indicating the event that occurred. Possible values for event codes are given in the event code enumeration (page 2-17).

result

For completion events, the result code of the completed provider function, identified by the code parameter. For completion events, the meaning of the result parameter is event specific. (For most asynchronous events, the result parameter has no meaning and can be ignored.) For additional information, see the description of the individual function.

cookie

A pointer to data. The meaning and type of the data vary depending on the function that has completed executing. For additional information, see the event codes enumeration (page 2-17).

DESCRIPTION

Using a notifier function is the recommended way for your application to handle completion and asynchronous events. After you install a notifier function for a provider, the function is called by the provider each time an Open Transport event occurs for that provider. For a completion event, the provider passes the function result in the result parameter, the event code in the code parameter, and any additional information in the cookie parameter. For an asynchronous event, the provider usually passes the event code in the code parameter and passes no other information.

Open Transport calls your notifier function at secondary interrupt level (deferred task time). For this reason, your notifier function is subject to the same rules and restrictions as are all Macintosh functions that can be called at interrupt time; these restrictions are summarized in the section "Using Notifier Functions to Handle Provider Events," beginning on page 2-12.

You can install the same notifier function for two or more providers. But each time you install the same notifier function for a different provider, you must pass a different value in the contextPtr parameter of the function that installs the notifier. The data structure referenced by the contextPtr parameter points must include a provider reference or some other identifier that uniquely identifies the provider for which the notifier is called.

SPECIAL CONSIDERATIONS

The following information applies to applications written for 68000-family machines. Before calling your notifier function, Open Transport restores the A5 register to the value it had when you installed the notifier function. Thus, if your development environment saves your application context in the A5 register, your notifier function need not restore its A5 world. But if your development environment saves your application context in a register other than A5, your notifier function must save and restore that register.

SEE ALSO

To install a notifier function for an existing provider, call the OTInstallNotifier function (page 2-39). You can also install a provider when you open a provider asynchronously by passing a pointer to the notifier function as a parameter to the function used to open the provider. For additional information, see the reference section of the chapter describing the provider of interest.

To remove a notifier function, call the OTRemoveNotifier function (page 2-41).

For a list and description of event codes see the event codes enumeration (page 2-17).

For an example of a notifier function, see Listing 2-1 on page 2-13.